1.1 Qu’est-ce c’est ?

La “fiche” est une publication didactique qui présente une méthodologie, un type d’analyse, une fonctionnalité, ou encore le traitement d’un certain type de données avec le langage R. Une fiche peut être principalement technique, méthodologique ou thématique ; elle peut également couvrir ces trois aspects. Elle est évaluée par au moins deux personnes ayant les connaissances thématiques nécessaires.

Le premier objectif d’une fiche consiste à partager de manière pédagogique des méthodes reproductibles applicables en SHS. La publication d’une fiche est ouverte à toutes et tous, quels que soient son statut et sa discipline. Une fiche peut être réalisée à plusieurs et présenter une dimension interdisciplinaire.

Les auteurs et autrices sont libres dans le choix de la problématique et dans la façon d’articuler le contenu. Il est cependant indispensable que le contenu soit correctement contextualisé et intelligible pour l’ensemble des disciplines de SHS. Il est également obligatoire de suivre les règles suivantes :

• utiliser le modèle de mise en page readrzine,
• rédiger en français ou en anglais,
• introduire et contextualiser le contenu,
• présenter du code entièrement reproductible,
• utiliser des données libres d’utilisation et mises à disposition des lecteurs et lectrices,
• fournir les fichiers et annexes demandées.

Vous pouvez consulter les premières fiches déjà produites pour vous faire une idée du résultat attendu :

• Analyse territoriale multiscalaire, Ronan Ysebaert et Claude Grasland.
  
• Analyse des corrélations avec easystats, Grégoire Le Campion.
  
• Exploration spatio-temporelle d’objets géographiques ponctuels, Marion Le Texier.
• Réaliser une carte de discontinuités en 2,5D, Nicolas Lambert.

Rzine souhaite promouvoir et partager des usages et pratiques de logiciels et méthodes contribuant à une science plus ouverte et reproductible, et participer à une montée en compétence des disciplines de SHS dans ce domaine. C’est pour cela que l’ensemble du processus d’évaluation se déroule sur GitHub qui repose sur le logiciel de gestion de versions Git. Cela ne doit en aucun cas effrayer les auteurs et autrices qui n’ont jamais utilisé Git : de la documentation et une assistance sont fournies par le comité de lecture Rzine… !

1.2 Critères d’acceptation

Afin d’assurer la cohérence et la qualité du contenu des fiches Rzine, plusieurs critères d’acceptation ont été définis. Certains de ces critères peuvent conduire au refus immédiat d’une proposition de fiche par le comité de lecture, d’autres critères font l’objet d’une analyse contradictoire par plusieurs évaluateur·rice·s.

Les éditeur·rice·s et les évaluateur·rice·s veilleront à ce que :

• la démonstration soit contextualisée (champ disciplinaire d’application) et rigoureuse,
• le code présenté se doit d’être lisible, commenté et reproductible,
• les packages mobilisés doivent être brièvement décrits et leur utilisation justifiée,
• les données ou jeux de données utilisés dans le cadre de la démonstration doivent obligatoirement être publiés, sourcés et librement réutilisables.

*Le cas échéant, le comité de lecture se réserve la possibilité de mettre en relation différent·es contributeurices pour leur proposer un travail collaboratif.

1.3 Soumission et évaluation

1.4 Publication et licence d’utilisation

Les choix des dépôts et licences d’utilisation s’inscrivent dans la volonté du projet Rzine de promouvoir des pratiques contribuant à une science plus ouverte et à la reproductibilité des méthodes. L’ensemble des publications de la collection Rzine avec leurs codes sources est automatiquement référencé et mis à disposition de toutes et tous. Afin d’éviter tout malentendu avec les auteurices, un accord de principe est demandé en amont du processus éditorial.

Etre auteurice d’une fiche Rzine, c’est accepter que :

• votre publication (HTML) soit mise à disposition sous les conditions d’utilisation de la licence Creative Commons BY-SA 4.0,

• les données et jeux de données associés ont été ou sont rendus publics, sont sourcés et leur réutilisation est libre,

• son code source réponde aux conditions d’utilisation de la licence MIT.

2.1 Installation du package rzine

Le package est mis à disposition sur un dépôt du groupe Rzine sur l’instance GitLab de la TGIR Huma-num. Pour l’installer et le charger il suffit de copier le code ci-dessous dans votre console R :

install.packages("remotes") # si le package `remotes` n'est pas encore installé
remotes::install_gitlab("rzine/package", host = "https://gitlab.huma-num.fr/", force = TRUE)
library(rzine)

2.2 Utiliser le template readrzine

2.2.1 Première étape : spécifier un répertoire de travail

Avant de générer une fiche Rzine vierge il est important de spécifier un répertoire de travail. Pour cela, deux solutions s’offrent à vous :

1. En clic-bouton avec Rstudio (recommandé)

Pour créer un projet Rstudio, cliquez sur File/New Project, sélectionnez New Directory, puis New Project :

La création du projet Rstudio engendre la création d’un répertoire au nom du projet et le paramétrage automatique de ce dossier comme répertoire de travail.

2. En ligne de code R

Créez un répertoire sur votre ordinateur puis spécifiez-le comme répertoire de travail avec la fonction setwd() dans votre console :

setwd("/home/jeanne/Documents/Fiche_rzine")

rmarkdown::draft(file = "index.Rmd", 
                 template = "readrzine", 
                 package = "rzine", 
                 create_dir = FALSE, 
                 edit = FALSE)

rmarkdown::render("index.Rmd", envir = new.env())

3.1 Métadonnées d’en tête

Commencez par modifier l’en-tête du template readrzine (YAML header), en personnalisant le titre, le sous-titre, le nom de ou des auteur.es et les affiliations, comme par exemple :

---
title: "Analyse textuelle exploratoire"
subtitle: "Exploration d'un corpus de lettre avec le package Quanteda"
date: "2023-10-09"
author: 
 - name: Jeanne Dupont
   affiliation: UMR TEXTO, CNRS
 - name: Paul Edouard
   affiliation: Centre documentaire ED, Université de France

3.2 Le résumé

Il est obligatoire de proposer un résumé en début de publication. Ce résumé sera utilisé pour la page de présentation de la fiche sur le site rzine.fr, pour le dépôt Github du code source (cf. exemple), du DOI et le référencement sur HAL.

Ce résumé doit faire entre 250 à 800 caractères (espaces comprises). Il peut comprendre des informations sur d’éventuels prérequis pour bien comprendre le document.

Pour mettre en forme votre résumé en introduction de fiche, utilisez le symbol “>” qui permet de créer un bloc de citation qui apparaîtra sur un fond gris. Exemple :

> Ce document... xx x xx x xx xxx xxxx xx xx xxxx x xx x xxx xxxx x xx xxx xxxx xx xx xxxx x xx x xxx

> **Prérequis** : xx x xx x xx xxx xxxx xx xx xxxx x xx x xxx xxxx x xx xxx xxxx xx xx xxxx x xx x xxx

Le bloc de citation apparaîtra comme suit :

Ce document… xx x xx x xx xxx xxxx xx xx xxxx x xx x xxx xxxx x xx xxx xxxx xx xx xxxx x xx x xxx

Prérequis : xx x xx x xx xxx xxxx xx xx xxxx x xx x xxx xxxx x xx xxx xxxx xx xx xxxx x xx x xxx

3.3 Contextualisation

Il est essentiel et obligatoire d’introduire et de contextualiser le contenu de votre document.

Vous pouvez pour cela vous appuyer sur des références bibliographiques, utiles pour les non-spécialistes de la thématique ou de la méthode présentée.

3.4 Données utilisées

<br/>

<p class="center">[<span style="font-size: 230%;" class="glyphicon glyphicon-download-alt"></span><br/>Télécharger les données](https://rzine.fr/docs/...../data.zip)</p>

<br/>

3.5 Packages et fonctions

Comme pour les données, il est important de consacrer un sous-chapitre aux packages utilisés. Tous les packages mobilisés pour l’analyse doivent être listés et décrits :
- package1 : description…
- package2 : description…
- package3 : description…

Tous les packages et fonctions explicitement nommés doivent également être mis en page de cette façon :

`packages` et `fonction()`

Voici le rendu : packages et fonction()

3.6 Illustration

<figure class="center">
  <img src="figures/rzine.png" width="200">
  
  <figcaption style="font-size:13px;">Logo de la collection Rzine, 2021,  [https://rzine.fr/collection/#collection](https://rzine.fr/collection/#collection){target="_blank"}</figcaption>

</figure>

3.7 Ecriture de code R

Le code R présenté dans la fiche doit être indenté, espacé et commenté. Il est demandé aux auteur·e·s de prendre soin de la syntaxe et de respecter les principales conventions d’écriture.

Pour en savoir plus, vous pouvez consulter The tidyverse style guide d’Hadley Wickham.

3.8 Message d’alerte

Il est possible d’utiliser certains messages d’alerte boostrap :

• Encadré vert (success) : pour mettre en avant une information
  
• Encadré rouge (danger) : our mettre en relief une information primordiale

La syntaxe HTML à utiliser est :

<div class="alert alert-success" role="alert">Message d'information</div>

**ET**
 
<div class="alert alert-danger" role="alert">Message <b>très important</b></div>

Voici le rendu :

ET

3.9 Formules mathématiques

Il est possible d’écrire des formules mathématiques en langage \(\TeX\). Il suffit de délimiter le contenu \(\LaTeX\) par un ou deux symboles $, ex :

$$ y = \sqrt{\frac{1}{x + \beta}} $$ 

En mode Inline (un seul $) , les formules sont incluses à l’intérieur du paragraphe courant, ex : \(\sum_{i=1}^n X_i\)
En mode Displayed (deux $), elles apparaissent centrées et mises en exergue, ex : \[ y = \sqrt{\frac{1}{x + \beta}} \]

3.10 Références bibliographiques

Le template readrzine intègre automatiquement une section de références bibliographiques. Il est fortement recommandé aux auteur·e·s de l’utiliser. Cependant cette section n’est pas obligatoire, vous pouvez supprimer les lignes suivantes dans le fichier index.rmd si vous ne souhaitez pas afficher de bibliographie :

# Bibliographie {-}

<div id="refs"></div>

Sinon, pour ajouter des références bibliographiques, complétez le fichier biblio.bib.

Trois références bibliographiques sont saisies par défaut dans le fichier biblio.bib :

@Manual{R-base,
  title = {R: A Language and Environment for Statistical Computing},
  author = {{R Core Team}},
  organization = {R Foundation for Statistical Computing},
  address = {Vienna, Austria},
  year = {2020},
  url = {https://www.R-project.org/},
}

@Manual{R-knitr,
  title = {knitr: A General-Purpose Package for Dynamic Report Generation in R},
  author = {Yihui Xie},
  year = {2020},
  note = {R package version 1.28},
  url = {https://CRAN.R-project.org/package=knitr},
}

@Manual{R-rmdformats,
  title = {rmdformats: HTML Output Formats and Templates for 'rmarkdown' Documents},
  author = {Julien Barnier},
  year = {2021},
  note = {R package version 1.0.2},
  url = {https://github.com/juba/rmdformats},
}

Beaucoup de documentation sur les fichiers BibTex sont consultables sur internet (exemple). Pour citer une référence dans le corps du texte, utilisez la syntaxe suivante : [@Citation Key]. Citation Key = nom de la référence dans le fichier BibTex (ex : R_base, R-knitr ou R-rmdformats). Par exemple, la chaîne de caractère [@R-base] affichera le lien (R Core Team 2020) dans le document.

Toutes les références bibliographiques renseignées dans le fichier biblio.bib seront automatiquement ajoutées dans la section « Bibliographie ».

3.11 Glossaire

Cette section n’est pas obligatoire, cependant vos lecteur.rices ne seront pas forcément issu·es de votre discipline ou ne maîtriseront peut-être pas la thématique ou méthode présentée. En définissant certains termes utilisés, la section « Glossaire » permet de rendre la démonstration compréhensible à un public plus large.

Pour ajouter un mot ou expression, ainsi que sa définition dans le Glossaire, utilisez la syntaxe markdown suivante :

texte texte texte mot à définir^[__Mot à définir__: Définition du terme... ]

A la compilation du document en format HTML, un numéro est automatiquement associé et affiché après le “mot à définir”. Ce mot/expression et sa définition sont ajoutés dans la section « Glossaire ». Exemple : Mot à définir¹

Si vous ne souhaitez pas utiliser de Glossaire, supprimez les lignes suivantes dans le fichier index.rmd :

## Glossaire {- #endnotes}

```{js, echo=FALSE}

$(document).ready(function() {
  $('.footnotes ol').appendTo('#endnotes');
  $('.footnotes').remove();
});

3.12 Informations sur la session

Cette section obligatoire est directement intégrée au template.

## Info session  {-}

```{r session_info, echo=FALSE}
kableExtra::kable_styling(knitr::kable(rzine::sessionRzine()[[1]], row.names = F))
kableExtra::kable_styling(knitr::kable(rzine::sessionRzine()[[2]], row.names = F))
```

Ce bout de code affiche des informations sur la session qui a permis de générer la fiche (système d’exploitation, versions de R et des packages utilisés). Voir l’exemple pour ce document.

3.13 Citation BibTex

Cette section obligatoire est directement intégrée au template.

## Citation {-}

```{r Citation, echo=FALSE}

rref <- bibentry(
   bibtype = "article",
   title = "Titre de la fiche",
   author = person("Auteur.e 1", "Auteur.e 2" ),
   journal = "Rzine.fr",
   publisher = "FR CIST",
   year = 2021,
   url = "https://...")

``` 

`r capture.output(print(rref))`

### BibTex : {-}

```{r generateBibTex, echo=FALSE}

writeLines(toBibtex(rref), "cite.bib")
toBibtex(rref)

``` 


<br/>

Ne mofifiez pas cette section, elle sera complétée avant publication par l’équipe éditoriale. Ces deux chunks permettent l’affichage de la référence bibliographique de votre fiche dans le corps du document (Voir l’exemple pour ce document), ainsi que le stockage de cette référence en format BibTex, enregistrée dans le fichier cite.bib à la racine du répertoire.

4.1 Premiers pas sur Github

Le logiciel de gestion de versions décentralisé que vous devez utiliser pour la soumission est GitHub.

4.2 Remplissage du dépôt

Vous pouvez désormais y ajouter le répertoire (et sous-répertoires) contenant tous les fichiers de votre fiche. Il existe plusieurs méthodes pour téléverser des fichiers sur GitHub (en ligne de commande ou en clic-bouton). Nous présentons ici la méthode clic-bouton depuis l’interface de GitHub.

Cliquez sur “Add file”, puis sur “Upload files” :.

Ajoutez un commentaire et cliquez sur “Commit changes” :

Vous venez de réaliser votre premier “commit” (enregistrement des changements). L’ensemble des fichiers est désormais stocké sur le dépôt :

Ce dépôt étant paramétré comme public, tout le monde peut désormais le consulter et récupérer les fichiers qu’il contient.

4.3 Déploiement de la fiche

Les fichiers sont consultables à l’état brut, mais une manipulation supplémentaire va permettre de mettre en ligne votre fiche (format HTML). Votre fiche mise en forme sera ainsi consultable par tout le monde sur le web, sans avoir à gérer un serveur ou un site web.

4.4 Soumettre

Il ne vous reste plus qu’à contacter le comité de lecture Rzine pour soumettre votre fiche pour évaluation. Envoyez un courriel à collection[a]rzine.fr, en précisant l’adresse du dépôt qui héberge votre fiche.

Vous serez contacté·e par le comité de lecture dans les 15 jours suivants l’envoi de ce courriel.

6.1 L’en-tête

L’en-tête d’un document R Markdown (parfois appelé YAML header) est délimité par deux lignes de trois tirets et contient des métadonnées et les éléments de style du document. Voici à quoi ressemble par exemple l’en-tête vierge du template readrzine :

---
title: "Titre fiche"
subtitle: "Sous-titre fiche"
date: "2023-10-09"
author: 
 - name: Premier Auteur.e
   affiliation: Affiliation_1, Affiliation_2
 - name: Second Auteur.e
   affiliation: Affiliation_1, Affiliation_2
image: "featured.png"   
logo: "figures/rzine.png"  
output:
  rzine::readrzine:
    highlight: kate
    number_sections: true
csl: Rzine_citation.csl
bibliography: biblio.bib
nocite: |
  @*
link-citations: true
# github: "author/repository"
# gitlab: "gitlab.huma-num.fr/author/repository"
# doi: "xx.xxx/xxxx.xxxxxxx"
# licence: "by-sa"

# Only Creative Commons Licence 
# 5 possible choices : "by-nd", "by", "by-nc-sa", "by-nc","by-sa"
---

6.2 Le texte balisé en markdown

Le corps d’un document R Markdown comprend deux types de contenu, que l’on peut librement alterner :

• Des blocs de texte brut mis en forme selon la syntaxe Markdown ;
  
• Des blocs de code, appelés chunks (cf. partie 3.3).

Le corps du document est constitué de texte mis en forme à l’aide de la syntaxe Markdown. Le Markdown est un langage de balisage léger et très facile à maîtriser, qui permet la mise en forme basique du texte.

Par exemple, le texte (brut) suivant :

Ceci est du texte en *italique*, **gras** ou en ***gras italique***.

Pour définir des listes à puces, utilisez les **tirets** :

- premier élément
- second élément

Vous pouvez également ajouter des [liens cliquables](https://rzine.fr/) 

Sera mis en page de la manière suivante dans le fichier HTML généré :

Ceci est du texte en italique, gras ou en gras italique.

Pour définir des listes à puces, utilisez les tirets :

• premier élément
• second élément

Vous pouvez également ajouter des liens cliquables

6.3 Les chunks

En plus du texte libre balisé en markdown, un document R Markdown peut évidemment contenir du code R.
Celui-ci doit être inclus dans des chunks délimités par la syntaxe suivante :

```{r}

x <- 37 + 12
print(x)

```

Pour insérer facilement un nouveau chunk, vous pouvez utiliser le menu Insert proposé par l’interface de développement RStudio, situé en haut à droite de l’éditeur de texte (à gauche du bouton Run) :

Vous pouvez également utiliser le raccourci clavier Ctrl + Alt + i ou Command + Option + I pour générer un chunk vide.

```{r nom_du_chunck_1}

```

```{r nom_du_chunck_2, echo = FALSE, warning = FALSE}

x <- 37 + 12
print(x)

```

6.4 Documentation de référence

Pour en savoir plus, pour se former au R Markdown et à la syntaxe markdown :

• Cookbook R Markdown, de Y. Xie, C. Dervieux & E. Riederer
• R Markdown Definitive Guide, de Y. Xie, J. J. Allaire & G. Grolemund
• R Markdown for Scientists, de Nicholas Tierney
• Introduction à R et au tidyverse, de Julien Barnier
• Travail collaboratif avec R, de Lino Galiana
• Pimp my RMD: a few tips for R Markdown, de Yan Holtz
• R for Data Science, de H. Wickham & G. Groelemund
• Guide de la syntaxe R Markdown, de Rstudio
• Guide de référence R Markdown, de Rstudio
• R Markdown Cheatsheet, de Rstudio
• Writing Reproducible Research Papers with R Markdown, de Resul Umit